fix: QoL improvements to make the SDK more stable #1014

dot-agi · 2025-05-28T17:43:58Z

📥 Pull Request

📘 Description
Enhanced AgentOps SDK reliability, consistency, and developer experience through comprehensive improvements across core functionality, error handling, and dependency management.

🔧 Core Infrastructure Improvements

Enhanced Error Handling: Improved TracingCore._flush_span_processors() with comprehensive exception handling for AttributeError, RuntimeError, and unexpected errors, enhanced logging levels, and graceful degradation to ensure span processor failures don't break application flow
Code Consolidation: Added format_trace_id() utility function to eliminate duplicate trace ID formatting logic across the codebase, improving maintainability and consistency
Resource Management: Removed deprecated LiveSpanProcessor class to simplify the processor architecture and reduce maintenance overhead

🎯 API Consistency & Backward Compatibility

Decorator Improvements: Enhanced @trace decorator with better error handling, proper cleanup in finally blocks, and improved async/sync function support
Deprecation Management: Added proper deprecation warnings for @session decorator while maintaining backward compatibility
Session Lifecycle: Improved trace context management with better cleanup and state tracking
Python Compatibility: Added typing_extensions>=4.0.0 for Python <3.11 compatibility, ensuring Required and NotRequired types work across all supported Python versions

🛡️ Reliability & Error Resilience

Graceful Degradation: Enhanced error handling ensures that telemetry failures don't break user applications
Resource Leak Prevention: Improved cleanup mechanisms in trace management to prevent resource leaks
Logging Improvements: Better structured logging with appropriate levels (debug, warning, error) for different failure scenarios

🧪 Testing
Comprehensive test coverage added to validate all improvements:

50+ new unit tests across 2 test modules covering edge cases, error conditions, and integration scenarios
Error Resilience Testing: Exception handling for AttributeError, RuntimeError, and unexpected errors during span processor operations (test_core_error_handling.py)
API Consistency Testing: Return value behavior validation, parameter passing, backward compatibility patterns, and exception propagation (test_init_api_consistency.py)
Integration Testing: Real-world usage patterns, shutdown behavior during active span processing, and graceful degradation scenarios
Backward Compatibility: Ensures existing user code continues to work without modifications

🔄 Migration Impact

Zero Breaking Changes: All changes maintain backward compatibility
Automatic Benefits: Users get improved reliability and error handling without code changes
Optional Upgrades: New dependency versions are available in dev-llm group for development environments
Deprecation Path: Clear migration path from @session to @trace decorator with helpful warnings

These changes address critical production issues including resource management, error propagation during shutdown scenarios, and dependency version gaps while maintaining full backward compatibility and improving the overall developer experience.

This reverts commit 5fa1cb8.

This reverts commit 339b3d1.

codecov · 2025-05-28T17:44:52Z

Codecov Report

Attention: Patch coverage is 69.18239% with 49 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
agentops/sdk/decorators/factory.py	54.28%	32 Missing ⚠️
agentops/legacy/__init__.py	75.00%	8 Missing ⚠️
agentops/client/client.py	56.25%	7 Missing ⚠️
agentops/sdk/types.py	71.42%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

Copilot

Pull Request Overview

Enhances SDK reliability by preventing resource leaks, improving error handling, and stabilizing the public API return value.

Adds timeout-based thread shutdown and logging in LiveSpanProcessor.shutdown
Refines TracingCore._flush_span_processors with granular exception handling and logging
Ensures agentops.init() consistently returns the client’s init() result across all code paths

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/test_init_api_consistency.py	Adds coverage for `agentops.init()` return-value behavior
tests/unit/sdk/test_live_span_processor_lifecycle.py	Verifies enhanced shutdown logic for LiveSpanProcessor
tests/unit/sdk/test_core_error_handling.py	Exercises new exception-handling paths in `TracingCore`
agentops/sdk/types.py	Switches to `Required[int]` for mandatory config fields
agentops/sdk/processors.py	Implements timeout and error handling in `shutdown()`
agentops/sdk/decorators/factory.py	Extracts session‐trace logic into sync/async helpers
agentops/sdk/decorators/init.py	Deprecates `@session` in favor of `@trace` with warning
agentops/sdk/core.py	Adds detailed logging and exception branches to flush API
agentops/sdk/converters.py	Introduces `format_trace_id` helper for ID formatting

Comments suppressed due to low confidence (2)

tests/unit/sdk/test_live_span_processor_lifecycle.py:18

Consider patching the logger in this test to assert that no warning or error is logged during a normal shutdown, ensuring false-positive logs are caught.

def test_shutdown_normal_thread_termination(self):

agentops/sdk/decorators/init.py:21

There’s no existing test verifying that the deprecated @session decorator emits a DeprecationWarning. Adding a unit test for that warning would ensure the deprecation path stays valid.

# For backward compatibility: @session decorator calls @trace decorator with deprecation warning

agentops/sdk/types.py

Copilot

Pull Request Overview

Enhancements focus on improving the SDK’s stability by preventing resource leaks, strengthening error handling, and ensuring consistent API behavior. Key changes include:

Enhancements to LiveSpanProcessor.shutdown() with timeout-based thread join and improved logging.
Comprehensive error handling improvements in TracingCore._flush_span_processors().
API consistency fixes for agentops.init() with associated test updates.

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/unit/test_init_api_consistency.py	Added extensive tests for various init() parameter and return patterns.
tests/unit/sdk/test_live_span_processor_lifecycle.py	Added tests for graceful shutdown and timeout handling for span processor.
tests/unit/sdk/test_core_error_handling.py	Expanded tests for error handling in _flush_span_processors.
agentops/sdk/types.py	Updated TypedDict definitions using new Required type hints.
agentops/sdk/processors.py	Refactored shutdown logic with timeout, exception handling and logging.
agentops/sdk/decorators/factory.py	Replaced inline session handling with dedicated helper functions.
agentops/sdk/decorators/init.py	Added deprecation warning for @session decorator.
agentops/sdk/core.py	Integrated format_trace_id() for improved trace id formatting.
agentops/sdk/converters.py	Added format_trace_id() utility function with robust error handling.

agentops/sdk/decorators/__init__.py

pyproject.toml

agentops/sdk/processors.py

tests/unit/sdk/test_live_span_processor_lifecycle.py

Copilot

Pull Request Overview

This PR enhances SDK stability and developer experience by improving core error handling, consolidating utility logic, and cleaning up deprecated components.

Strengthened _flush_span_processors with detailed exception handling and standardized trace ID formatting via format_trace_id().
Removed deprecated LiveSpanProcessor and centralized trace ID formatting in a new converter.
Refactored session tracing in decorators to helper functions and updated dependencies for Python <3.11.

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/unit/test_init_api_consistency.py	Added comprehensive tests for `agentops.init()` return consistency.
tests/unit/sdk/test_core_error_handling.py	New tests covering all error scenarios in `_flush_span_processors`.
pyproject.toml	Added `typing_extensions` dependency and defined `dev-llm` group.
agentops/sdk/types.py	Updated `TracingConfig` fields to use `Required[int]`.
agentops/sdk/processors.py	Removed deprecated `LiveSpanProcessor` class.
agentops/sdk/decorators/factory.py	Extracted sync/async session-trace logic into helpers.
agentops/sdk/decorators/init.py	Changed deprecation log level for `@session` and cleaned imports.
agentops/sdk/core.py	Enhanced `force_flush` error handling and integrated `format_trace_id`.
agentops/sdk/converters.py	Introduced `format_trace_id` utility with error handling.

Comments suppressed due to low confidence (2)

agentops/sdk/decorators/init.py:22

[nitpick] The session decorator no longer uses functools.wraps(trace), causing wrapped functions to lose metadata (name, docstring). Consider reintroducing @functools.wraps(trace) to preserve transparent decorator behavior.

def session(*args, **kwargs):

agentops/sdk/core.py:337

The return under the hasattr check is misaligned by one indentation level, which can cause a syntax error. Align it under the if not hasattr(self._provider, 'force_flush'): block.

            return

This reverts commit c184be2.

agentops/sdk/decorators/factory.py

dot-agi · 2025-06-07T13:53:45Z

Closing this because it's scraping the bottom of the barrel. Too many conflicts to invest time into and a better quality PR is needed.

dot-agi added 11 commits May 28, 2025 13:22

fix session decorator resource management

f5c1458

fix api consistency issues in decorators/__init__.py

5fa1cb8

deprecation warning when using session decorator

9d46fba

make int as Required

811bffa

use method to format trace id

3b9585d

improved error handling in span processor flushing

9f4d307

prevent resource leak in LiveSpanProcessor

4148fe5

better method to create span

339b3d1

Revert "fix api consistency issues in decorators/__init__.py"

bf850af

This reverts commit 5fa1cb8.

Revert "better method to create span"

c9a0532

This reverts commit 339b3d1.

add some tests

d7f20df

dot-agi requested a review from Dwij1704 May 28, 2025 17:43

dot-agi added the enhancement New feature or request label May 28, 2025

dot-agi requested a review from Copilot May 28, 2025 17:44

Copilot AI reviewed May 28, 2025

View reviewed changes

agentops/sdk/types.py Outdated Show resolved Hide resolved

remove Annotated

d4fd257

dot-agi requested a review from Copilot May 28, 2025 17:48

Copilot AI reviewed May 28, 2025

View reviewed changes

dot-agi added 2 commits May 28, 2025 23:25

bad GitHub copilot

f2dcc41

add compatibility for both Python <3.11 and >=3.11

3cc4bf8

Dwij1704 requested changes May 29, 2025

View reviewed changes

agentops/sdk/decorators/__init__.py Outdated Show resolved Hide resolved

pyproject.toml Show resolved Hide resolved

agentops/sdk/processors.py Show resolved Hide resolved

tests/unit/sdk/test_live_span_processor_lifecycle.py Outdated Show resolved Hide resolved

Dwij1704 requested a review from areibman May 29, 2025 09:58

Merge branch 'main' into fix/stable-sdk-fixes

9881aa5

dot-agi added the do not merge label May 29, 2025

dot-agi added 2 commits May 29, 2025 17:57

use logger instead of warnings

de37a13

purge LiveSpanProcessor from codebase

4829179

dot-agi requested a review from Dwij1704 May 29, 2025 13:55

dot-agi removed the do not merge label May 29, 2025

add dev-llm to make @Dwij1704 happy :)

c184be2

dot-agi requested a review from Copilot May 29, 2025 17:43

Copilot AI reviewed May 29, 2025

View reviewed changes

dot-agi force-pushed the fix/stable-sdk-fixes branch from f30cd59 to c184be2 Compare May 29, 2025 18:14

dot-agi added 5 commits May 29, 2025 23:46

Revert "add dev-llm to make @Dwij1704 happy :)"

9ecfeb9

This reverts commit c184be2.

Merge branch 'main' into fix/stable-sdk-fixes

96629d9

Merge branch 'main' into fix/stable-sdk-fixes

58bbb7a

import functools

21bf90d

Merge branch 'main' into fix/stable-sdk-fixes

7d90392

bboynton97 reviewed Jun 4, 2025

View reviewed changes

agentops/sdk/decorators/factory.py Outdated Show resolved Hide resolved

bboynton97 mentioned this pull request Jun 4, 2025

investigate ways to clean sdk #1036

Closed

dot-agi added 2 commits June 5, 2025 04:11

@bboynton97 use the new tracer variable pls #1030

dc35730

Merge branch 'main' into fix/stable-sdk-fixes

c7cd7e3

bboynton97 approved these changes Jun 7, 2025

View reviewed changes

dot-agi closed this Jun 7, 2025

dot-agi deleted the fix/stable-sdk-fixes branch June 7, 2025 13:53

dot-agi linked an issue Jun 9, 2025 that may be closed by this pull request

investigate ways to clean sdk #1036

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: QoL improvements to make the SDK more stable #1014

fix: QoL improvements to make the SDK more stable #1014

Uh oh!

dot-agi commented May 28, 2025 •

edited

Loading

Uh oh!

codecov bot commented May 28, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

dot-agi commented Jun 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fix: QoL improvements to make the SDK more stable #1014

fix: QoL improvements to make the SDK more stable #1014

Uh oh!

Conversation

dot-agi commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📥 Pull Request

🔧 Core Infrastructure Improvements

🎯 API Consistency & Backward Compatibility

🛡️ Reliability & Error Resilience

Uh oh!

codecov bot commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

dot-agi commented Jun 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dot-agi commented May 28, 2025 •

edited

Loading

codecov bot commented May 28, 2025 •

edited

Loading